<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>Putting Records Using Cursors</title>
    <link rel="stylesheet" href="gettingStarted.css" type="text/css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.62.4" />
    <link rel="home" href="index.html" title="Getting Started with Berkeley DB" />
    <link rel="up" href="Cursors.html" title="Chapter 9. Using Cursors" />
    <link rel="previous" href="Positioning.html" title="Getting Records Using the Cursor" />
    <link rel="next" href="DeleteEntryWCursor.html" title="Deleting Records Using Cursors" />
  </head>
  <body>
    <div class="navheader">
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">Putting Records Using Cursors</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="Positioning.html">Prev</a> </td>
          <th width="60%" align="center">Chapter 9. Using Cursors</th>
          <td width="20%" align="right"> <a accesskey="n" href="DeleteEntryWCursor.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="sect1" lang="en" xml:lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both"><a id="PutEntryWCursor"></a>Putting Records Using Cursors</h2>
          </div>
        </div>
        <div></div>
      </div>
      <p>
        You can use cursors to put records into the database. DB's behavior
        when putting records into the database differs depending on the flags
        that you use when writing the record, on the access method that you are
        using, and on whether your database supports sorted duplicates.
    </p>
      <p>
        Note that when putting records to the database using a cursor, the
        cursor is positioned at the record you inserted. 
    </p>
      <div class="itemizedlist">
        <ul type="disc">
          <li>
            <p>
            <tt class="methodname">Cursor.putNoDupData()</tt>
            
         </p>
            <p>
            If the provided key  already exists 
            in the database, then this method returns 
            <tt class="literal">OperationStatus.KEYEXIST</tt>.
        </p>
            <p>
            If the key does not exist, then the order that the record is put into the database 
            is determined by the 
                
                <span>
                    insertion order in use by the database. If a comparison
                    function has been provided to the database, the record is
                    inserted in its sorted location. Otherwise (assuming BTree), 
                    lexicographical sorting is used, with
                    shorter items collating before longer items.
                </span>
         </p>
            <p>
            This flag can only be used for the BTree and Hash access methods,
            and only if the database has been configured to support sorted
            duplicate data items (<tt class="literal">DB_DUPSORT</tt> was specified at
            database creation time).
        </p>
            <p>
            This flag cannot be used with the Queue or Recno access methods.
        </p>
            <p>
            For more information on duplicate records, see
            <a href="btree.html#duplicateRecords">Allowing Duplicate Records</a>.
        </p>
          </li>
          <li>
            <p>
            <tt class="methodname">Cursor.putNoOverwrite()</tt>
         </p>
            <p>
            If the provided key already exists 
            in the database, then this method returns 
            .
        </p>
            <p>
            If the key does not exist, then the order that the record is put into the database 
            is determined by the BTree (key) comparator in use by the database. 
         </p>
          </li>
          <li>
            <p>
            <tt class="methodname">Cursor.putKeyFirst()</tt>
            
        </p>
            <p>
            For databases that do not support duplicates, this method behaves
                
                <span>
                    exactly the same as if a default insertion was performed.
                </span>
                If the database supports duplicate records, 
                    
                    <span>
                        and a duplicate sort function has been specified, the
                        inserted data item is added in its sorted location. If
                        the key already exists in the database and no duplicate
                        sort function has been specified, the inserted data item
                        is added as the first of the data items for that key.
                    </span>
        </p>
          </li>
          <li>
            <p>
            <tt class="methodname">Cursor.putKeyLast()</tt>
            
        </p>
            <p>
            Behaves exactly as if 
                 
                <tt class="methodname">Cursor.putKeyFirst()</tt>
            was used, except that if the key already exists in the database and no
            duplicate sort function has been specified, the
            inserted data item is added as the last of the data
            items for that key.
        </p>
          </li>
        </ul>
      </div>
      <p>For example:</p>
      <a id="java_cursor7"></a>
      <pre class="programlisting">package db.GettingStarted;
    
import com.sleepycat.db.Cursor;
import com.sleepycat.db.Database;
import com.sleepycat.db.DatabaseEntry;
import com.sleepycat.db.OperationStatus; 

...
  
// Create the data to put into the database
String key1str = "My first string";
String data1str = "My first data";
String key2str = "My second string";
String data2str = "My second data";
String data3str = "My third data";
  
Cursor cursor = null;
Database myDatabase = null;
try {
    ...
    // Database open omitted for brevity
    ...

    DatabaseEntry key1 = new DatabaseEntry(key1str.getBytes("UTF-8"));
    DatabaseEntry data1 = new DatabaseEntry(data1str.getBytes("UTF-8"));
    DatabaseEntry key2 = new DatabaseEntry(key2str.getBytes("UTF-8"));
    DatabaseEntry data2 = new DatabaseEntry(data2str.getBytes("UTF-8"));
    DatabaseEntry data3 = new DatabaseEntry(data3str.getBytes("UTF-8"));

    // Open a cursor using a database handle
    cursor = myDatabase.openCursor(null, null);

    // Assuming an empty database.

    OperationStatus retVal = cursor.put(key1, data1); // SUCCESS
    retVal = cursor.put(key2, data2); // SUCCESS
    retVal = cursor.put(key2, data3); // SUCCESS if dups allowed, 
                                      // KEYEXIST if not.    
                                              
} catch (Exception e) {
    // Exception handling goes here
} finally {
   // Make sure to close the cursor
   cursor.close();
}</pre>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="Positioning.html">Prev</a> </td>
          <td width="20%" align="center">
            <a accesskey="u" href="Cursors.html">Up</a>
          </td>
          <td width="40%" align="right"> <a accesskey="n" href="DeleteEntryWCursor.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">Getting Records Using the Cursor </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> Deleting Records Using Cursors</td>
        </tr>
      </table>
    </div>
  </body>
</html>
